home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 2 / AACD 2.iso / AACD / Magazine / GraphicsCards / StormMesa / README.WIN32 < prev    next >
Text File  |  1998-12-15  |  22KB  |  525 lines
  1.  
  2. Mesa/Readme.win32 - 7/23/98 - Theodore A. Jump - tjump@spgs.com
  3.  
  4.     Win32 builds of Mesa 3.0 are now running! - yay!
  5.  
  6.     Note: while this build set supports generation of a 3Dfx specific
  7.           DLL using Mesa, David Bucciarelli's original build files
  8.           are the "supported" method. -Ted
  9.  
  10.     NEW: Build GLUT standalone for use with system OpenGL and GLU drivers!
  11.          Command-line project supports building all test/demo programs
  12.          against these drivers also! This allows you full use of GLUT on
  13.          Windows using hardware accelerated OpenGL. Wheee!
  14.  
  15.     NEW: Microsoft Windows fxMesa-in-a-window hack! - if you want fxMesaGL
  16.          to render using the 3Dfx Voodoo1 or Voodoo2 hardware into a window
  17.          on the desktop then all you need to do is set the MESA_WGL_FX
  18.          environment variable to anything other than "fullscreen" and it
  19.          will render into a window.  If you wish to go fullscreen then you
  20.          only need to NOT have the environment variable, or have it set
  21.          to "fullscreen".  You may also switch at runtime between full-mode
  22.          and windowed by pressing ALT-ENTER on the keyboard.
  23.  
  24.     NEW: Microsoft Windows fxMesa dual-monitor support. If the Glide
  25.          environment variable SST_DUALHEAD is set to '1' then fxMesa will
  26.          never disable the Voodoo output on a Voodoo1 or Voodoo2 display
  27.          regardless of whether the fxMesa application is "current" or not.
  28.  
  29. *** Legalese
  30.  
  31. These build files are provided as-is and are submitted to be included with
  32. the "Mesa 3-D Graphics Library" package as (currently) maintained by Brian
  33. Paul. These project build files are free software; you can redistribute it
  34. and/or modify it under the terms of the GNU Library General Public License
  35. as published by the Free Software Foundation; either version 2 of the
  36. License, or (at your option) any later version.
  37.  
  38. These project files are distributed in the hope that they will be useful,
  39. but WITHOUT ANY WARRANTY; without even the implied warranty of
  40. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
  41. General Public License for more details.
  42.  
  43. You should have received a copy of the GNU Library General Public License
  44. along with this library; if not, write to the Free Software Foundation,
  45. Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  46.  
  47. *** Maintenance Responsiblity and Technical Support
  48.  
  49. While these files are now part of the Mesa core distribution please do NOT
  50. contact Mr. Paul for help with them if you encounter problems as he can't
  51. help you (currently).  I will, however, attempt my straightforward best in
  52. assisting anyone with using these files on their system.  I can NOT
  53. guarantee instant responses owing to other responsiblities, but I do try
  54. dang hard to answer any mail w/in 24 hours.  I may be contacted at the
  55. above email address for the forseeable future.
  56.  
  57. -Ted
  58. mailto://tjump@spgs.com
  59. http://www.i21.com/~tjump
  60.  
  61. *** General Information
  62.  
  63. These build files facilitate convenient building of many variants of Mesa,
  64. both as static link libraries (including mesaglu) and as dynamic link
  65. libraries that in some cases may be used as "drop-in" replacements for
  66. OpenGL32.DLL on both Windows95 and Windows NT.
  67.  
  68. The construction of the Win32 command-line build files and projects has
  69. been something of a pet project of mine, and is based upon my own
  70. "standard" Win32 build environment as supplied by the "nmake.mif" file.
  71. They have been tested under Windows95 OSR2, Windows NT 4.0SP3, and Windows
  72. NT 5.0 beta 1.  The libraries that they generated have been tested (via the
  73. demo programs) in a *limited* fashion on the above three systems, including
  74. the 3Dfx versions.
  75.  
  76. The reason I went with command-line build environment instead of the more
  77. convenient IDE-based project files is for two reasons: 1. These appear to
  78. have some amount of portability between versions (the nmake syntax hasn't
  79. changed much since Microsoft C 7.0) while the IDE project files seem to
  80. change drastically each version. and 2. These are readable with any ascii
  81. editor and such are better self-documentation of the file relationships for
  82. more people such that it will facilitate supporting other Win32 compilers.
  83.  
  84. While these files only deal with building for x86 targeted code it *should*
  85. be possible to add the necessary logic to them to build for the other MSVC
  86. supported CPU targets, I simply have no hardware to test them on nor the
  87. alternative compilers to build with.
  88.  
  89. *** Prerequisites for use
  90.  
  91. 1. You must have a 32-bit Microsoft compiler installed. I have tested
  92. this with Visual C 5.0 (SP3) and Visual C 4.2, but with minor
  93. (possibly no) modification to the nmake.mak and nmake.mif files this
  94. sequence should work on Visual C 2.0 also. The workspace files
  95. (mesalib.dsw and mesademos-*.dsw) and their included project files
  96. (*.dsp) are specific to the DevStudio IDE - I have made no attempt at
  97. building a VC4 IDE project set as I do not use that any more.  Note
  98. that the VC workspace files NO LONGER use NORE are dependant upon the
  99. nmake.mak and nmake.mif files for construction of definition (*.DEF)
  100. and resource (*.RC) files.
  101.  
  102. *** Visual C 4.x Users Warning ****
  103.  
  104. Note that early editions of VC4 do NOT have header files current enough
  105. for use building this code base. If you are using VC4 you will either need
  106. to get an update to version 4.2 *or* you may download the Platform SDK
  107. directly from Microsoft's web site (www.microsoft.com) and update your
  108. build environment that way.
  109.  
  110. *** Visual C 4.x Users Warning ****
  111.  
  112. 2. You must have the PATH, INCLUDE, and LIB environment variables set
  113. properly. With VC5 you can easily get this by executing the VCVARS32.BAT
  114. file that was created for you upon installation. It is found in the
  115. DevStudio\VC\BIN directory, wherever you installed DevStudio. VC4 provides
  116. a similar batch file in it's BIN directory also.
  117.  
  118. 3. (optional) If you're going to build for 3Dfx/Voodoo you will need to
  119. have previously installed the Glide SDK version 2.3 or later, if I
  120. recall. This may be retrieved from www.3dfx.com for no money and some
  121. download time. ;-) These build files assume that you have the Glide SDK
  122. added to the respective environment variables (LIB and INCLUDE).
  123.  
  124. 4. (optional) If you're going to build for S3/Virge you will need the S3
  125. Developers Toolkit which may be downloaded from www.s3.com for the price of
  126. registering on-line and some time. NOTE: I can build the s3mesa.dll file to
  127. completion, however the compilation of s3mesa.c currently generates a large
  128. amount of compiler warnings and between that and the fact that I can not at
  129. all test it I can make no claims to it's ability to execute.  Again, like
  130. the 3Dfx version before this, these build files assume you have the S3Dtk H
  131. and LIB files in the path of their respective environment variables.
  132. Note 2: As of Mesa3.0beta6 I have build files, both command-line and IDE,
  133. which should be able to build the s3mesa code base if it weren't for updates
  134. being required in the S3 DD code support (Mesa-3.0/src/s3 directory).
  135.  
  136. I advise putting any include and lib files for secondary toolkits (Glide,
  137. S3Tk, whatever) in their respective environment variables *before* the
  138. Microsoft-assigned default values.
  139.  
  140. *** Included programs that exhibit unfortunate or bad behavior
  141.  
  142. - demos/bounce - doesn't run on high-colors screens?  It's requesting an
  143.   INDEX display from GLUT and that fails on my true-color desktop. Changing
  144.   this to _RGB let's the program work, but it doesn't display
  145.   properly. This is probably just an idiosyncracy of my machine though, as
  146.   if I test the program using GLUT for System OpenGL on my Intel740 OpenGL
  147.   accelerated machine it's just hunky-dory.
  148.  
  149. - demos/glutfx - runs, but crashes on exit (but not on my Intel740 machine)
  150.  
  151. - demos/texobj - runs, but crashes on exit if ESC is pressed. Exits cleanly
  152.   if the Close box on the window frame is pressed with the mouse. Go figure.
  153.  
  154. - book/aaindex - doesn't run, can't get pixel format, because it wants an
  155.   INDEX display maybe (but is okay on my Intel740 machine)?
  156.  
  157. - moves of the book/* demos don't respond to ESC being pressed.
  158.  
  159. - 3dfx/demos/* - all demos run, however they all crash on exit. I've traced
  160.   this so far as to determine the call it's happening with. The crash comes
  161.   from within Glide during the processing of the grGlideShutdown() call, as
  162.   in invalid memory reference exception. I'm wondering if this is because
  163.   of some state or processing not being completed before the call. Dunno,
  164.   but putting grSstIdle() in just before grGlideShutdown() does NOT fix the
  165.   problem.
  166.  
  167. - 3dfx/demos/tunnel2 - does not run on my system even with SLI mode
  168.   disabled. Hmmmm, maybe I need to disconnect my Voodoo2 cards?
  169.  
  170. *** Important Notes and Changing Default values
  171.  
  172. - The optimizer settings have been manually reworked in both command line
  173.   and DevStudio IDE files to hopefully prevent possible irrational code on
  174.   the part of the code generator.  Formerly, it was configured for "/Ox",
  175.   now it is configured for
  176.  
  177. - These files build with the code targeted for Pentium processors and
  178.   8-byte structure padding.
  179.  
  180. - The IDE-built programs seem to be "happier" in that the command line
  181.   build of the 3Dfx demo "fire" will grenade on exit (?). Otherwise pretty
  182.   much everything may be built with either interface.
  183.  
  184. - The currently configured Mesa version is 3.0beta6, and MesaDemos version
  185.   is the same. To change this permanently you will need to edit NMAKE.MAK
  186.   and change the lines that look like this (they start o/a line 116):
  187.  
  188.     # Currently, Mesa is at rev 3.0 ...
  189.     #
  190.     !IF "$(MESAVER)" == ""
  191.     MESAVER=3.0
  192.     !ENDIF
  193.  
  194.     # used in building all of the resource files for the Mesa DLLs
  195.     #
  196.     !IF "$(MESAFILEVER)" == ""
  197.     MESAFILEVER=3,0,0,0
  198.     !ENDIF
  199.  
  200.     # Currently, MesaDemos are at rev 3.0 ..
  201.     #
  202.     !IF "$(MESADEMOVER)" == ""
  203.     MESADEMOVER=3.0
  204.     !ENDIF
  205.  
  206.     # used in building all of the resource files for the Aux & Tk DLLs
  207.     #
  208.     !IF "$(MESADEMOFILEVER)" == ""
  209.     MESADEMOFILEVER=3,0,0,0
  210.     !ENDIF
  211.  
  212. - Currently the build files are configured to be used from a Win32
  213.   directory that is included inside the main Mesa-3.0 heirarchy.
  214.  
  215. - The build files are smart enough to find the files for the core lib, glu,
  216.   glut, and the various demo programs if they are unpacked in the current
  217.   Mesa-3.0 heirarchy, like this:
  218.  
  219.     \Mesa-3.0
  220.     \Mesa-3.0\src
  221.     \Mesa-3.0\src-glu
  222.     \Mesa-3.0\src-glut
  223.     \Mesa-3.0\Win32
  224.     \Mesa-3.0\samples
  225.     \Mesa-3.0\demos
  226.     \Mesa-3.0\book
  227.     \Mesa-3.0\3Dfx\demos
  228.  
  229.     ... should work.  This arose because my initial build tests for the
  230.     demo files were done before MesaDemos 2.6 had been released.
  231.  
  232. - To enable use of MMX instructions by the VC5 compiler you may add the
  233.   "USE_MMX=1" option to the NMAKE command line, or edit the default in the
  234.   NMAKE.MAK file.  This does appear to have some affect on the performance
  235.   on the library and does not seem to harm it in any way *but* I have done
  236.   *no* verification of this. I have an MMX processor so I figured what the
  237.   heck. This option is only available with VC5 when building from the
  238.   command line.
  239.  
  240.   This is probably required if you are going to modify the code to include
  241.   inline MMX instructions though.
  242.  
  243. - With the exception of the static link libraries generated by this file
  244.   set (mesagl.lib, mesaglu.lib, mesaglut.lib) all DLLs and executables are
  245.   built against the "Multithreaded DLL" runtime - this means that they
  246.   required MSVCRT.DLL or MSVCRTD.DLL in the path to execute.
  247.  
  248.   Note also that the demos are all built aginst the Mesaxxx.lib variants to
  249.   ensure that they do *NOT* use system GLU/OpenGL libs. If you want that,
  250.   you will need to modify the link parameters. The exception to this rule
  251.   (aren't there always) is when you build the 'progs.sgigl' or
  252.   'progs.sysgl' targets, these do *NOT* use Mesa at all in the end.
  253.  
  254. - The 3Dfx build of Mesa has primarily been tested with Quake 2 and it runs
  255.   fine on my PC (take that for what you want it)...
  256.  
  257. - I can not test the S3 build as I have no machines available with Virge
  258.   based display cards.
  259.  
  260. - The multithreaded test code is *not* built as it requires pthreads and I
  261.   have as of yet spent not time trying to get that running. The latest word
  262.   that I saw WRT threading support on win32 was that they are intending to
  263.   support it natively within Win32 - so I'm waiting it out until they get
  264.   it done.
  265.  
  266. - Similarly, the 'xdemos' are not currently built because I haven't gotten
  267.   around to building the client libs for native win32 and getting it all
  268.   setup for use.
  269.  
  270. - The OpenGL32.DLL, GLU32.DLL, and GLUT32.DLL files are alias builds, for
  271.   conveniences, of the MesaGL32.DLL, MesaGLU32.DLL, and . The demo files
  272.   are linked against the prior set to facilitate them working with
  273.   different OpenGL driver files (e.g.: you can copy in the fxMesaGL32.DLL
  274.   or s3MesaGL32.DLL if you want).  Some of the demo programs will NOT work
  275.   without Mesa itself as they utilize Mesa-specific functions, most however
  276.   will work with any full GL implementation.
  277.  
  278. *** Output Files
  279.  
  280. All files are generated and, with the exception of the executable images,
  281. are copied in the the "root intermediate file directory" upon
  282. completion. This upshot of this is that if you build everything in it's
  283. default settings you end up with a copy of all .LIB and .DLL files
  284. generated in ".\win32\release" and these may then be copied to more
  285. permanent places for use in your own programs.
  286.  
  287. The executable images are copied back to their own source directories so
  288. that they may find any local data files necessary (texture maps, surface
  289. maps, whatever) upon execution.  Note that since they are linked against
  290. DLL files you will either need to add the .\win32\release directory to you
  291. path before execution or copy the respective DLL files form .\win32\release
  292. to somewhere in your path.
  293.  
  294. Because I'm anal about my computer and it's organization, and I like to
  295. prevent collision between builds, each of the subprojects has their own
  296. intermediate file directory inside .\win32\release (for example, when
  297. building mesagl.lib all of it's intermediate files will be found in
  298. .\win32\release\lib.mesagl).  This makes it very easy to cleanup as you
  299. only need to remove .\win32\release.
  300.  
  301. *** Okay, Enough, how do I build with this stuff already Ted!
  302.  
  303. Okay, no major calamity here. The basic way to use the project file is to
  304. call it via NMAKE from the command line. The format is:
  305.  
  306.     nmake[.exe] /f nmake.mak [options] [target]
  307.  
  308. The most likely [options] values you will use may be any combination of the
  309. following:
  310.  
  311.     DEBUG=1 or DEBUG=0
  312.     USE_MMX=1 or USE_MMX=0
  313.     USE_CRTDLL=1 or USE_CRTDLL=0
  314.  
  315.     Note that all three of these options are OFF by default.
  316.  
  317. The [target] includes but is not limited to the following (for full details
  318. please peruse the NMAKE.MAK and NMAKE.MIF files - but be warned that
  319. NMAKE.MIF is rather large and sometimes hard to follow):
  320.  
  321.     --- convenience targets ---
  322.  
  323.     all                 - builds everything
  324.     libfiles            - builds all linking library files
  325.     progs               - builds all executable images
  326.  
  327.     --- library files, static and dynamic ---
  328.  
  329.     mesagl              - static lib build of Mesa core.
  330.     mesaglu             - static lib build of MesaGLU core.
  331.     mesaglut            - static lib build of Mesa GLUT core.
  332.  
  333.     mesagl32, mesaglu32,
  334.     mesaglut32          - dynamic lib build each lib
  335.  
  336.     opengl32, glu32, glut32
  337.                         - alias builds of each lib that allow for
  338.                           convenient replacement of the base opengl32.dll
  339.                           with the 3Dfx or S3 builds.
  340.  
  341.     --- hardware accelerated mesa builds ---
  342.  
  343.     fxmesagl32          - builds Mesa for use on top of the 3Dfx
  344.                           Glide runtime libs
  345.  
  346.     s3mesagl32          - builds mesa for use on top of the S3
  347.                           'S3Tk' runtime libs.
  348.  
  349.     --- executable images ---
  350.  
  351.     progs.book          - builds all programs in \book directory
  352.     progs.demos         - builds all programs in \demos directory
  353.     progs.samples       - builds all programs in \samples directory
  354.  
  355.         These generate all of the programs in their respective
  356.         directories and link the executables against mesa32.dll,
  357.         mesaglu32.dll, and mesaglut32.dll and are thus
  358.         hard-bound to the CPU-based image generation.
  359.  
  360.     progs.3dfx.demos    - builds all programs in \3dfx\demos directory
  361.  
  362.         The following program-generating targets link the executables
  363.         against glut32.lib, glu32.lib, opengl32.lib, glide2x,lib,
  364.         texus.lib, and winmm.lib and are thus NOT hard-bound to using
  365.         Mesa per-se as you can simply replace the opengl32.dll file in
  366.         use - but I would definately make sure whichever one I was using
  367.         had hardware acceleration.
  368.  
  369.    --- Microsoft/SGI OpenGL-based GLUT and Demo program builds ----
  370.  
  371.    *** IMPORTANT SAFETY TIP: If you're going to build these variants of
  372.        GLUT then DO NOT build any other target libraries in this package
  373.        first, OR from the command line run the "nmake /f nmake.mak clean"
  374.        command first!  This is because generation of the GLUT for SGI
  375.        OpenGL target libraries conflicts in naming with the static build
  376.        libraries of Mesa and it's supporting GLUT build.
  377.  
  378.    Currently, you may build GLUT as either GLUT32.DLL or GLUT.DLL for
  379.    use running against either Microsoft or SGI OpenGL for Window,
  380.    respectively.  This allows for the general use of GLUT 3.7 on Windows
  381.    systems with fully compliant OpenGL.
  382.  
  383.    You can build the GLUT DLL files either with the command line by
  384.    issuing either of these commands:
  385.  
  386.         nmake /f nmake.mak glut.sysgl
  387.  
  388.         <or>
  389.  
  390.         nmake /f nmake.mak glut.sgigl
  391.  
  392.    OR by using the DevStudio MesaLib Worksapce build the GLUT_SGIGL or
  393.    GLUT_SYSGL projects within the DevStudio IDE.
  394.  
  395.    Unfortunately, the only way to build the test programs against this
  396.    build of GLUT is via the command line, and I will NOT be making
  397.    duplicate demo program projects for the IDE as it's just not worth it,
  398.    sorry.
  399.  
  400.    To build the test programs against either MS or SGI OpenGL, you do so
  401.    via either of these two commands:
  402.  
  403.         nmake /f nmake.mak progs.sysgl
  404.  
  405.         <or>
  406.  
  407.         nmake /f nmake.mak progs.sgigl
  408.  
  409.    To use the GLUT-for-system-OpenGL in your own programs, you need to do
  410.    three things by way of preparation, after building GLUT of course:
  411.  
  412.          1. Copy include\gl\glut.h to somewhere in your %INCLUDE% path, one
  413.             likely candidate location would be in your
  414.             "DevStudio\VC\INCLUDE\GL" directory.
  415.  
  416.          2. Copy the linking libraries to somewhere in your %LIB% path, one
  417.             likely candidate location would be in your "DevStudio\VC\LIB"
  418.             directory. The linking libraries you need to copy are as
  419.             follows:
  420.  
  421.                 .\Release\GLUT32.LIB
  422.                 .\Release\GLUT.LIB
  423.                 .\Debug\GLUT32.LIB
  424.                 .\Debug\GLUT.LIB
  425.  
  426.         3. Copy the runtime libraries to somewhere in your %PATH%, one
  427.            likely candidate location would be in WINDOWS\SYSTEM. the files
  428.            that you should copy are as follows:
  429.  
  430.                 .\Release\GLUT32.DLL
  431.                 .\Release\GLUT32.PDB
  432.                 .\Release\GLUT.DLL
  433.                 .\Release\GLUT.PDB
  434.                 .\Debug\GLUT32d.DLL
  435.                 .\Debug\GLUT32d.PDB
  436.                 .\Debug\GLUTd.DLL
  437.                 .\Debug\GLUTd.PDB
  438.  
  439. Some examples are in order ...
  440.  
  441.     ... build all static-link libs using MMX support:
  442.  
  443.         nmake /f nmake.mak USE_MMX=1 allstatic
  444.  
  445.     ... build all dynamic-link libs using MSVCRT.DLL for C runtime,
  446.         also build with MMX support:
  447.  
  448.         nmake /f nmake.mak USE_MMX=1 USE_CRTDLL=1 alldynamic
  449.  
  450.     ... build all 3Dfx target DLL files with debugging support:
  451.  
  452.         nmake /f nmake.mak DEBUG=1 allfx
  453.  
  454.     ... To build all library variants and all test and demonstration
  455.         programs with the default settings you do this:
  456.  
  457.         nmake /f nmake.mak all
  458.  
  459.     ... to build all static link libs and nothing else you do this:
  460.  
  461.         nmake /f nmake.mak allstatic
  462.  
  463.     ... to build all non-accelerated dynamic link libs you do this:
  464.  
  465.         nmake /f nmake.mak alldynamic
  466.  
  467.     ... to build all 3Dfx targeted dynamic link libs you do this:
  468.  
  469.         nmake /f nmake.mak allfx
  470.  
  471.     ... to build all S3 Virge targetd dynamic link libs you do this:
  472.  
  473.         nmake /f nmake.mak alls3
  474.  
  475.     ... to build all libraries, static and dynamic, in all versions
  476.         you do this:
  477.  
  478.         nmake /f nmake.mak libfiles
  479.  
  480.     ... to subsequently build all demo and test programs you do this:
  481.  
  482.         nmake /f nmake.mak progs
  483.  
  484.     ... to cleanup all intermediate files you do this:
  485.  
  486.         nmake /f clean
  487.  
  488. You get the picture. (I hope) ;^)  You may also specify specify
  489. single targets in a convenient fashion. The rule is simple, any of the
  490. above named lib files, static or dynamic, may be built by providing it's
  491. name on the command line as the target. Examples:
  492.  
  493.     ... to build only Mesa as OpenGL32.DLL ...
  494.  
  495.         nmake /f nmake.mak opengl32
  496.  
  497.     ... to build only Mesa on top of the 3Dfx Glide API ...
  498.  
  499.         nmake /f nmake.mak fxMesa32
  500.               <or>
  501.         nmake /f nmake.mak fxMesa
  502.  
  503.     ... to build only Mesa on top of the S3 Toolkit ...
  504.  
  505.         nmake /f nmake.mak s3Mesa32
  506.               <or>
  507.         nmake /f nmake.mak s3mesa
  508.  
  509. *** Revision history for ./win32 project files
  510.  
  511. 1/18/98 - initial cut submitted and included with core mesa
  512. 2/5/98  - fixed internal dependency within nmake.mif upon there being
  513.           a $(DEVDIR) variable to make some temporary batch files
  514.           dependant upon (thanks to Keven T. McDonnell for finding
  515.           that there was this particular bug). I also updated the
  516.           build files for 2.6beta6.
  517. 2/8/98  - added DevStudio workspace and project files for all lib
  518.           files and some test programs. Updated readme.win32.
  519. 6/25/98 - initial revision for Mesa 3.0, does not include IDE files,
  520.           not everything is running. *sigh*
  521. 7/20/98 - Mesa 3.0beta6 rev of all build files, all libs built and
  522.           minimally tested, all demo programs built and minimally
  523.           tested to within limits of my PC. ;^) Eveything looks
  524.           MUCH better now ...
  525.